@theseus.run/jsx-md 0.1.2 → 0.2.1

package/README.md

@@ -1,81 +1,14 @@
 # `@theseus.run/jsx-md`
 
-Built to manage agent instructions across multiple harnesses — [Copilot](https://github.com/features/copilot), [OpenCode](https://opencode.ai), and others. The content wasn't the problem. The management was.
+JSX runtime that outputs Markdown strings — typed props, Context API, XML intrinsics, zero runtime dependencies.
 
-Agent instruction files grow. They develop conditional sections — capabilities that only apply to one harness, traits you're toggling between first-person and third-person to test what produces better behavior. A shared fragment between two agents becomes a copy-paste. A conditional becomes a ternary inside a template literal:
+→ [Why this exists](https://romanonthego.dev/blog/jsx-that-outputs-markdown)
 
-```typescript
-const instructions = `
-You are a code reviewer.
+## Prior art
 
-${harness === 'opencode' ? '<!-- use task() for subtasks -->' : ''}
+[dbartholomae/jsx-md](https://github.com/dbartholomae/jsx-md) (2019, inactive) and [eyelly-wu/jsx-to-md](https://github.com/eyelly-wu/jsx-to-md) are built for documentation generation — READMEs, changelogs. They work well for that. `dbartholomae/jsx-md` predates `jsxImportSource` and uses file-level pragma comments; its `render()` returns a Promise.
 
-## Traits
-${firstPerson
-  ? '- I always verify output before claiming done.'
-  : '- The agent must verify output before claiming done.'}
-`
-```
-
-No syntax highlighting for the Markdown inside the string. No types on the structure. A variant is a new file. Refactoring is grep-and-pray.
-
-Nested lists make it worse. Markdown requires exact indentation — two spaces per level. Template strings force you to hardcode that spacing:
-
-```typescript
-const instructions = `
-## Rules
-
-- Outer rule
-  - Nested rule: two hardcoded spaces
-    - Deeper: four hardcoded spaces
-${condition ? '  - Conditional nested item' : ''}
-`
-```
-
-A false conditional leaves a blank bullet. The indentation is load-bearing and invisible. `DepthContext` in `@theseus.run/jsx-md` tracks nesting depth automatically — you write `<Ul>` inside `<Li>` and the renderer handles the spaces.
-
-This isn't an edge case. [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) — 39.8k stars, serious harness work — stores instructions the same way:
-
-```typescript
-export const PROMETHEUS_HIGH_ACCURACY_MODE = `# PHASE 3: PLAN GENERATION
-## High Accuracy Mode - MANDATORY LOOP
-\`\`\`typescript
-while (true) {
-  const result = task(subagent_type="momus", ...)
-  if (result.verdict === "OKAY") break
-}
-\`\`\`
-...` // 62 more lines of escaped template string
-```
-
-The escaped backticks are the tell — not a bad solution, it's the only solution the format offers. No composability, no reuse, no tooling support.
-
-The web dev world solved "structured text with conditionals and composable fragments" ten years ago. JSX is a transform spec, not a React dependency — `jsxImportSource` lets you point it at any runtime. `@theseus.run/jsx-md` is a runtime that outputs Markdown:
-
-```tsx
-const ReviewerInstructions = ({ harness, firstPerson }: Props) => (
-  <>
-    <P>You are a code reviewer.</P>
-    {harness === 'opencode' && (
-      <HtmlComment>use task() for subtasks</HtmlComment>
-    )}
-    <H2>Traits</H2>
-    <Ul>
-      <Li>
-        {firstPerson
-          ? 'I always verify output before claiming done.'
-          : 'The agent must verify output before claiming done.'}
-      </Li>
-    </Ul>
-  </>
-)
-
-render(<ReviewerInstructions harness="opencode" firstPerson={true} />)
-```
-
-No escaped backticks. Syntax highlighting in your editor. Conditionals are JSX expressions. Variants are props. Shared fragments are components.
-
-`render()` returns a plain string — no virtual DOM, no hydration, no React runtime anywhere in the chain.
+`@theseus.run/jsx-md` targets agent instructions assembled at call time: `render()` is synchronous, Context API ships with it, and any lowercase tag is an XML intrinsic.
 
 ---
 
@@ -83,9 +16,17 @@ No escaped backticks. Syntax highlighting in your editor. Conditionals are JSX e
 
 ```bash
 bun add @theseus.run/jsx-md
+# npm install @theseus.run/jsx-md
+# pnpm add @theseus.run/jsx-md
+```
+
+**AI coding agent skill** (OpenCode, Cursor, Copilot, Claude Code):
+
+```bash
+npx skills add https://github.com/theseus-run/theseus/tree/master/packages/jsx-md
 ```
 
-Then in `tsconfig.json`:
+`tsconfig.json`:
 
 ```json
 {
@@ -96,84 +37,71 @@ Then in `tsconfig.json`:
 }
 ```
 
----
-
-## What you're getting
-
-**Zero runtime dependencies.** The package ships TypeScript source with no third-party imports. Nothing gets added to your bundle.
-
-**Bun-first.** Ships TypeScript source directly, no compiled output. Works transparently in Bun: install, add two tsconfig lines, write TSX. The trade-off is real: vanilla Node.js without a bundler won't run `.ts` files from `node_modules`. If your stack is Vite, tsup, or esbuild, those handle it. If you're running bare Node, v0.1.0 doesn't have a solution for you yet.
-
-**JSX without React.** When you write `<H2>Title</H2>`, the transform calls `jsx(H2, { children: "Title" })`. `H2` is a plain function — takes props, returns a string. No virtual DOM, no reconciler, no fiber, no hooks. `render()` walks the VNode tree synchronously and concatenates. The output is deterministic: same input, same string, every time. You can test it with `expect(render(<MyPrompt />)).toMatchSnapshot()`.
-
-**TypeScript-first.** All components and their props are typed. `render()` accepts `VNode`, returns `string`. Wrong usage is a compile error, not a runtime surprise.
-
-**String children are verbatim.** `render()` passes raw string values through without escaping. `<P>{"<b>text</b>"}</P>` outputs `<b>text</b>` — no transformation. For LLM prompts this is the right default; Markdown renderers handle the rest.
-
-**XML-structured prompts, zero config.** Any lowercase JSX tag renders as an XML block — `<context>`, `<instructions>`, `<example index={1}>`. Anthropic's prompt engineering guide recommends this structure for Claude agents. Attributes are typed and serialized automatically; empty tags self-close. No imports, no registration — it's built into the JSX intrinsics catch-all.
+Ships TypeScript source and compiled ESM output with sourcemaps. Bun resolves the TypeScript source directly. Node.js (≥18) and bundlers (Vite, tsup, esbuild) use the compiled output — no configuration needed, the `exports` map handles it transparently.
 
 ---
 
 ## Usage
 
 ```tsx
-// system-prompt.tsx
 import { render, H2, P, Ul, Li, Bold, Code } from "@theseus.run/jsx-md";
 
-const prompt = render(
+const ReviewerPrompt = ({ repo }: { repo: string }) => (
   <>
     <H2>Role</H2>
-    <P>
-      You are a precise code reviewer. Your job is to find bugs, not suggest
-      style changes.
-    </P>
+    <P>You are a precise code reviewer. Find bugs, not style issues.</P>
 
     <H2>Rules</H2>
     <Ul>
-      <Li>
-        Flag <Bold>P0</Bold> issues immediately — do not bury them.
-      </Li>
-      <Li>
-        Use <Code>inline code</Code> when referencing identifiers.
-      </Li>
+      <Li>Flag <Bold>P0</Bold> issues first — do not bury them.</Li>
       <Li>One finding per comment. No compound observations.</Li>
+      <Li>Use <Code>inline code</Code> when referencing identifiers.</Li>
     </Ul>
-
-    <H2>Output format</H2>
-    <P>
-      Respond with a structured list. Each item: severity, location, finding.
-    </P>
   </>
 );
 
-console.log(prompt);
+const prompt = render(<ReviewerPrompt repo="cockpit" />);
+// "## Role\n\nYou are a precise code reviewer..."
 ```
 
-Output:
+`render()` returns a plain string. No virtual DOM, no React runtime. Same input, same string, every time.
+
+---
 
-```markdown
-## Role
+## Context API
 
-You are a precise code reviewer. Your job is to find bugs, not suggest style changes.
+Avoids prop-drilling through shared fragment trees. Same shape as React — `createContext`, `useContext`, `Context.Provider` — synchronous, no rules-of-hooks.
 
-## Rules
+```tsx
+import { render, createContext, useContext, Ul, Li, Code } from "@theseus.run/jsx-md";
 
-- Flag **P0** issues immediately — do not bury them.
-- Use `inline code` when referencing identifiers.
-- One finding per comment. No compound observations.
+const HarnessCtx = createContext<'opencode' | 'copilot'>('copilot');
 
-## Output format
+const StepsSection = () => {
+  const harness = useContext(HarnessCtx);
+  return (
+    <Ul>
+      <Li>Always verify output before claiming done.</Li>
+      {harness === 'opencode' && <Li>Use <Code>task()</Code> for multi-step subtasks.</Li>}
+    </Ul>
+  );
+};
 
-Respond with a structured list. Each item: severity, location, finding.
+// Wire it once at the root — no prop threading:
+const prompt = render(
+  <HarnessCtx.Provider value="opencode">
+    <StepsSection />
+  </HarnessCtx.Provider>
+);
 ```
 
----
+`useContext` returns the default when called outside a Provider. Providers nest — innermost wins.
 
-## Structured agent instructions
+---
 
-Anthropic's prompt engineering guide recommends XML tags to structure Claude prompts — wrapping each content type in its own tag reduces misinterpretation. `<instructions>`, `<context>`, `<examples>`, `<document index="n">` are the documented patterns.
+## XML intrinsics
 
-Any lowercase JSX tag is an XML intrinsic in `@theseus.run/jsx-md`. No imports, no registration:
+Any lowercase JSX tag renders as an XML block. No imports, no registration:
 
 ```tsx
 const ReviewerPrompt = ({ repo, examples }: Props) => (
@@ -185,13 +113,6 @@ const ReviewerPrompt = ({ repo, examples }: Props) => (
     <instructions>
       <H2>Role</H2>
       <P>You are a precise code reviewer. Find bugs, not style issues.</P>
-
-      <H2>Rules</H2>
-      <Ul>
-        <Li>Flag <Bold>P0</Bold> issues first — do not bury them.</Li>
-        <Li>One finding per comment. No compound observations.</Li>
-        <Li>Use <Code>inline code</Code> when referencing identifiers.</Li>
-      </Ul>
     </instructions>
 
     {examples.length > 0 && (
@@ -204,120 +125,73 @@ const ReviewerPrompt = ({ repo, examples }: Props) => (
       </examples>
     )}
   </>
-)
-```
-
-Output:
-
-```
-<context>
-Repository: cockpit. Language: TypeScript. Package manager: bun.
-</context>
-
-<instructions>
-## Role
-
-You are a precise code reviewer. Find bugs, not style issues.
-
-## Rules
-
-- Flag **P0** issues first — do not bury them.
-- One finding per comment. No compound observations.
-- Use `inline code` when referencing identifiers.
-</instructions>
-
-<examples>
-  <example index="1">
-    ... your example content ...
-  </example>
-</examples>
+);
 ```
 
-Attributes are typed (`index={1}` → `index="1"`), boolean `true` attrs render bare, `false`/`null`/`undefined` are omitted. Empty tags self-close: `<tag />`.
+Attributes are typed — `index={1}` serializes to `index="1"`. Boolean `true` renders bare, `false`/`null`/`undefined` are omitted. Empty tags self-close.
 
 ---
 
 ## Primitives
 
-| Component | Markdown output |
-|-----------|----------------|
+| Component | Output |
+|---|---|
 | `H1`–`H6` | `#`–`######` headings |
 | `P` | Paragraph (blank line separated) |
 | `Hr` | `---` horizontal rule |
-| `Codeblock` | Fenced code block with optional `lang` prop |
+| `Codeblock` | Fenced code block (`lang` prop optional) |
 | `Blockquote` | `>` blockquote |
 | `Ul` | Unordered list |
-| `Ol` | Ordered list |
-| `Li` | List item (supports nesting via `Ul`/`Ol` inside `Li`) |
+| `Ol` | Ordered list (auto-numbered, nesting supported) |
+| `Li` | List item (supports nested `Ul` or `Ol` inside `Li`) |
 | `TaskList` | Task list container |
 | `Task` | `- [ ]` / `- [x]` task item (`done` prop) |
 | `Table` | Markdown table |
 | `Tr` | Table row |
-| `Th` | Table header cell |
+| `Th` | Table header cell (`align`: `left`, `center`, `right`) |
 | `Td` | Table data cell |
 | `Bold` | `**bold**` |
 | `Code` | `` `inline code` `` |
 | `Italic` | `*italic*` |
 | `Strikethrough` | `~~strikethrough~~` |
+| `Br` | Hard line break (`  \n` — two trailing spaces) |
+| `Sup` | `<sup>content</sup>` superscript |
+| `Sub` | `<sub>content</sub>` subscript |
+| `Kbd` | `<kbd>content</kbd>` keyboard key |
+| `Escape` | Escapes CommonMark metacharacters in children |
 | `Link` | `[text](url)` |
 | `Img` | `![alt](src)` |
-| `Md` | Raw markdown passthrough (escape hatch for complex inline combinations) |
-| `HtmlComment` | `<!-- comment -->` (invisible to most renderers; useful for LLM-only instructions) |
+| `Md` | Raw Markdown passthrough — renders verbatim, no transformation |
+| `HtmlComment` | `<!-- comment -->` — invisible to most renderers, useful for LLM-only instructions |
 | `Details` | `<details><summary>` collapsible block |
-| `Callout` | GitHub-style admonition with `type` prop: `note`, `tip`, `important`, `warning`, `caution` |
+| `Callout` | GitHub-style admonition (`type`: `note`, `tip`, `important`, `warning`, `caution`) |
 
 ---
 
-## Roadmap
-
-**v0.1.0** — current. TypeScript source, Bun-first. Markdown primitives + XML intrinsic elements.
-
-**v0.2.0** — two additions:
-
-- _Context API (public)._ `DepthContext` already uses an internal context system for list nesting. v0.2.0 exposes this as a first-class public API. The pattern is React-familiar but synchronous and string-based.
+## Utilities
 
-  Should fix prop-drilling. A prompt tree with conditional sections per harness ends up threading `harness` through every component:
+### `escapeMarkdown(s: string): string`
 
-  ```tsx
-  // v0.1.0 — prop-drilling
-  const Prompt = ({ harness }: Props) => (
-    <>
-      <Instructions harness={harness} />
-      <Rules harness={harness} />
-      <Examples harness={harness} />
-    </>
-  )
-  ```
+Escapes all CommonMark ASCII punctuation metacharacters with a backslash so user-supplied strings are treated as literal text by any markdown renderer.
 
-  With the v0.2.0 context API, set it once at the root and read it anywhere:
+```tsx
+import { escapeMarkdown, Escape, P } from "@theseus.run/jsx-md";
 
-  ```tsx
-  // v0.2.0 — context
-  const HarnessContext = createContext<'opencode' | 'copilot'>('copilot')
+// Function form
+const safe = escapeMarkdown(untrustedInput); // "**bold**" → "\\*\\*bold\\*\\*"
 
-  const prompt = render(
-    <HarnessContext.Provider value="opencode">
-      <Prompt />
-    </HarnessContext.Provider>
-  )
+// Component form — same result, composable in JSX
+render(<P>File: <Escape>{untrustedFilename}</Escape></P>);
+```
 
-  // In any component, at any depth — no prop threading:
-  const Instructions = () => {
-    const harness = useContext(HarnessContext)
-    return harness === 'opencode'
-      ? <P>Use task() for subtasks.</P>
-      : null
-  }
-  ```
+Escaped characters: `` \ ` * _ [ ] ( ) # + - . ! | ~ < > ``
 
-- _Node.js compiled output._ Ships a compiled `dist/` alongside the TypeScript source. Unblocks bare Node.js without a bundler.
+`&` is intentionally not escaped — use `escapeHtmlContent` for HTML contexts.
 
 ---
 
 ## License
 
-MIT — see [LICENSE](../../LICENSE). 
-
-Built by [Roman Dubinin](https://romanonthego.com). 
+MIT — see [LICENSE](../../LICENSE).
 
-Part of [Theseus](https://theseus.run).
+Built by [Roman Dubinin](https://romanonthego.dev). Part of [Theseus](https://theseus.run).

package/dist/index-8tdwjkh9.js

@@ -0,0 +1,11 @@
+// src/jsx-runtime.ts
+var Fragment = Symbol("Fragment");
+function jsx(type, props) {
+  return { type, props };
+}
+var jsxs = jsx;
+
+export { Fragment, jsx, jsxs };
+
+//# debugId=A10E4D57EB3603AA64756E2164756E21
+//# sourceMappingURL=index-8tdwjkh9.js.map

package/dist/index-8tdwjkh9.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/jsx-runtime.ts"],
+  "sourcesContent": [
+    "/**\n * Custom JSX-to-VNode runtime for agent markdown generation.\n *\n * Bun's JSX compilation with `jsxImportSource: \"@theseus.run/jsx-md\"` resolves\n * `jsx` and `jsxs` from `@theseus.run/jsx-md/jsx-runtime`. The factory builds\n * a VNode tree — no evaluation at construction time.\n *\n * Call `render(node)` from `./render.ts` to produce the final markdown string.\n * All markdown primitives live in primitives.tsx as named components.\n *\n * Fragment is a Symbol. render.ts imports this Symbol and handles it explicitly,\n * keeping the dependency one-way: render.ts → jsx-runtime.ts (no cycle).\n */\n\n// ---------------------------------------------------------------------------\n// VNode types\n// ---------------------------------------------------------------------------\n\n/**\n * The concrete runtime shape of a JSX element — what the `jsx()` factory always produces.\n *\n * Useful for structural inspection of a VNode tree (e.g. testing whether a node is an\n * element rather than a string, null, or array). The `isVNodeElement` predicate in\n * render.ts narrows to this type.\n *\n * @remarks **Do not use as a component return-type annotation.** TypeScript infers\n * `JSX.Element` (= `VNode`) as the return type of JSX expressions, not `VNodeElement`.\n * Annotating a component as `(): VNodeElement` causes TS2322 because `VNode` (the\n * inferred type) is not assignable to the narrower `VNodeElement`. Use `VNode` instead:\n * ```ts\n * // Wrong — TS2322\n * function MyComp(): VNodeElement { return <P>hi</P>; }\n * // Correct\n * function MyComp(): VNode { return <P>hi</P>; }\n * ```\n */\nexport type VNodeElement = {\n  readonly type: Component | string | typeof Fragment;\n  readonly props: Record<string, unknown>;\n};\n\nexport type VNode =\n  | null\n  | undefined\n  | boolean\n  | string\n  | number\n  | VNodeElement\n  | ReadonlyArray<VNode>;\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype Component<P = any> = (props: P) => VNode;\n\n// ---------------------------------------------------------------------------\n// JSX namespace\n// ---------------------------------------------------------------------------\n\n// eslint-disable-next-line @typescript-eslint/no-namespace\nexport namespace JSX {\n  /**\n   * JSX.Element is VNode so that components returning any valid VNode\n   * (string, VNodeElement, Fragment, null, etc.) satisfy TypeScript's\n   * component return-type check. The jsx() factory always produces\n   * VNodeElement at runtime; the wider union is only for type-checking.\n   */\n  export type Element = VNode;\n\n  // Catch-all — allows arbitrary lowercase XML tags as intrinsic elements.\n  export interface IntrinsicElements {\n    [tag: string]: { children?: VNode; [attr: string]: unknown };\n  }\n\n  export interface ElementChildrenAttribute {\n    children: VNode;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Fragment symbol\n// ---------------------------------------------------------------------------\n\n/**\n * Fragment — a unique Symbol used as the `type` of JSX fragment VNodes.\n * render.ts detects this Symbol and renders children directly, with no wrapper.\n * Using a Symbol (rather than a function) eliminates the circular dependency\n * that previously required _render-registry.ts.\n */\nexport const Fragment = Symbol('Fragment');\n\n// ---------------------------------------------------------------------------\n// JSX factory\n// ---------------------------------------------------------------------------\n\n/**\n * JSX factory — called by Bun's compiled JSX. Builds VNode tree; no evaluation.\n *\n * `type` is a function component, a string tag name, or the Fragment symbol.\n * String tags are rendered as XML blocks by render.ts: `<tag attrs>\\ncontent\\n</tag>\\n`\n * (or self-closing when the inner content is empty).\n */\nexport function jsx(\n  type: Component | string | typeof Fragment,\n  props: Record<string, unknown>,\n): VNodeElement {\n  return { type, props };\n}\n\n/** jsxs — same as jsx, used when there are multiple children (children is array) */\nexport const jsxs = jsx;\n"
+  ],
+  "mappings": ";AAuFO,IAAM,WAAW,OAAO,UAAU;AAalC,SAAS,GAAG,CACjB,MACA,OACc;AAAA,EACd,OAAO,EAAE,MAAM,MAAM;AAAA;AAIhB,IAAM,OAAO;",
+  "debugId": "A10E4D57EB3603AA64756E2164756E21",
+  "names": []
+}